AI Common Notify 完全指南：统一 AI 编程工具通知服务

在 AI 辅助编程日益普及的今天，Claude Code、Cursor、Windsurf、Trae 等 AI 工具极大地提升了我们的开发效率。但这些工具都有一个共同的问题：它们在执行完任务后不会主动通知用户，导致开发者需要手动检查任务状态。如果在同时运行多个任务时，容易错过重要信息或无法有效安排工作优先级。

为了解决这一问题，本人写了 AI Common Notify —— 一个为所有主流 AI 编程工具提供统一通知服务的开源工具。它能在 AI 工具完成任务后主动发送系统通知，让您在多任务并行时也能井然有序地处理工作。

p-cc
p-cursor

AI Common Notify 本质上是一个通知应用工具，因此它也可以不只应用于 ai 编辑器。

项目地址：https://github.com/MichealWayne/ai-common-notify

为什么选择 AI Common Notify？

现状问题

目前市面上虽然已有一些小的通知工具，但它们通常只针对单一 AI 工具，例如仅支持 Claude Code。这种碎片化的解决方案带来了以下问题：

  1. 工具割裂：每个 AI 工具需要单独的通知服务、如配 hook、配 mcp，用户需要安装和配置多个工具
  2. 体验不一致：不同通知服务的样式、行为和配置方式差异很大
  3. 维护成本高：当需要调整通知设置时，需要逐一修改各个工具的配置
  4. 扩展性差：缺乏统一的扩展机制，难以集成自定义通知渠道

AI Common Notify 的核心优势

AI Common Notify 针对上述痛点提供了全面解决方案：

  1. 统一接口：一个工具支持所有主流 AI 编程工具（Claude Code、Cursor、Windsurf、Trae 等）
  2. 跨平台兼容：支持 Windows、macOS 和 Linux
  3. 高度可配置：支持自定义标题、消息模板、紧急程度、超时时间、声音和图标
  4. 扩展性强：通过脚本回调机制，可轻松集成微信通知、钉钉机器人等自定义通知渠道
  5. 易于部署：支持 npm 全局安装和独立可执行文件，一键配置
  6. 智能初始化：自动检测项目中使用的 AI 工具并生成相应配置

快速入门

安装

在本地环境安装Nodejs（推荐 v18 及以上）后，可通过 npm 全局快速安装：

1
npm install -g ai-common-notify

验证安装

安装完成后，通过以下命令验证是否安装成功：

1
2
# 查看版本信息
ai-common-notify --version
1
2
# 发送测试通知
ai-common-notify test

如果看到版本信息或系统通知弹出，说明安装成功。

核心功能详解

1. 多样化的通知触发机制

AI Common Notify 支持多种通知触发方式，适配不同 AI 工具的特点：

Hook 模式（Claude Code）

可通过ai-common-notify quickInit命令在项目下快速初始化配置

通过 Claude Code 的 Hook 系统集成，在任务完成时发送通知：

在 Claude Code 设置文件 (~/.claude/settings.json 或项目中的 .claude/settings.json)设置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "hooks": {
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "ai-common-notify hook"
          }
        ]
      }
    ]
  }
}

MCP 模式（Cursor、Windsurf、Trae、CodeBuddy、Gemini-cli 等）

也可通过ai-common-notify quickInit命令在项目下快速初始化配置

通过在 IDE 中设置 MCP 为 Cursor 等工具提供通知服务：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "NotificationServer": {
      "command": "ai-common-notify",
      "args": ["mcp"]
    }
  }
}

使用提示：当使用 Cursor 或 Windsurf 等 MCP 工具时，建议在您的提示（prompt）最后明确要求发送通知，例如：”最后，任务完成时发送通知给我。“、”Finally, send me a notification when the task is finished.“ 这有助于确保 AI 工具调用通知工具。您也可以在 Cursor 的设置中将此提示添加为规则，这样就不需要每次都手动输入。

API 模式（自定义集成）

api 模式主要用于在线的平台工具进行调用，以统一通知处理。AI Common Notify 提供 RESTful API 供自定义工具调用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 启动API服务器
ai-common-notify api

# 发送通知请求
curl -X POST http://localhost:6001/api/v1/notify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{
    "title": "任务完成",
    "message": "代码重构已完成",
    "urgency": "normal",
    "timeout": 0,
    "sound": true
  }'

2. 灵活的通知定制

AI Common Notify 支持丰富的通知定制选项：

基础参数

  • title: 通知标题
  • message: 通知内容
  • urgency: 紧急程度（low/normal/critical）
  • timeout: 超时时间（秒，0 表示永久显示）（部分系统不适用）
  • sound: 是否播放声音
  • icon: 自定义图标路径（部分系统不适用）

高级配置

通过 JSON 配置文件实现更精细的控制：

1
2
3
4
5
6
7
8
9
{
  "notifications": {
    "default_timeout": 0,
    "default_sound": true,
    "default_urgency": "normal",
    "title_template": "{tool_name} - {project_name}",
    "message_template": "{message}"
  }
}

3. 脚本回调扩展

脚本回调在 AI Common Notify 的配置文件中设置，通过脚本回调扩展可以实现在通知发送时执行自定义脚本，让我们可以轻松集成微信通知、钉钉机器人等自定义通知渠道：

shell:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "scripts": {
    "timeout": 30000,
    "notify": [
      {
        "type": "shell",
        "path": "/path/to/your/script.sh",
        "enabled": true
      }
    ]
  }
}

nodejs:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "scripts": {
    "timeout": 30000,
    "notify": [
      {
        "type": "node",
        "path": "/path/to/your/script.js",
        "enabled": true
      }
    ]
  }
}

脚本中可以接收丰富的环境变量（如 nodejs 可以用process.env获取）：

  • NOTIFY_TITLE: 通知标题
  • NOTIFY_MESSAGE: 通知消息
  • NOTIFY_URGENCY: 紧急程度
  • NOTIFY_TIMEOUT: 超时时间
  • NOTIFY_SOUND: 是否播放声音
  • NOTIFY_PROJECT_NAME: 项目名称
  • NOTIFY_TOOL_NAME: 工具名称
  • NOTIFY_TIMESTAMP: 时间戳

通过脚本回调扩展我们可以额外完成很多自定义功能，如：

集成微信通知示例

Node.js 脚本示例（发送到企业微信）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// wechat-notify.js
const https = require('https');

// 企业微信机器人Webhook地址
const webhookUrl = 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY';

// 构造消息内容
const message = {
  msgtype: 'text',
  text: {
    content: `[${process.env.NOTIFY_TIMESTAMP}] ${process.env.NOTIFY_TITLE}\n${process.env.NOTIFY_MESSAGE}\n项目: ${process.env.NOTIFY_PROJECT_NAME}\n工具: ${process.env.NOTIFY_TOOL_NAME}`,
  },
};

// 发送请求
const data = JSON.stringify(message);
const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
  },
};

const req = https.request(webhookUrl, options, res => {
  console.log(`微信通知发送状态: ${res.statusCode}`);
});

req.on('error', error => {
  console.error('微信通知发送失败:', error);
});

req.write(data);
req.end();

个人开发者也可以考虑接入 PushPlus、WxPusher、Server 酱这类集成好的平台来实现微信等推送。

wechat-notification

4. 快速初始化功能

AI Common Notify 提供了一键初始化功能，自动为项目中检测到的 AI 工具生成或更新配置文件：

1
2
3
4
5
6
7
8
9
10
# 导航到项目目录
cd /path/to/your/project

# 初始化所有检测到的工具
ai-common-notify quickInit

# 初始化特定工具
ai-common-notify quickInit --tool cursor
ai-common-notify quickInit --tool claudecode
ai-common-notify quickInit --tool windsurf

该功能支持的工具包括：

  • Cursor: 通过 MCP 协议集成
  • Claude Code: 通过 Hook 系统集成
  • Windsurf: 通过 MCP 协议和规则文件集成
  • Gemini-cli: 通过 MCP 协议集成

5. 错误日志管理

AI Common Notify 具备完善的错误处理和日志记录功能，以便问题反馈和排查：

1
2
3
4
5
# 查看错误日志
ai-common-notify errlog

# 查看所有日志
ai-common-notify alllog

详细配置说明

配置层级

AI Common Notify 支持多层级配置，优先级从低到高依次为：

  1. 全局配置: ~/.config/ai-common-notify/config.json (Linux/macOS) 或 %APPDATA%\\ai-common-notify\\config.json (Windows)
  2. 项目配置: <project-root>/.ai-notify.json

配置文件示例

全局配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "server": {
    "port": 6001,
    "host": "localhost",
    "token": "generated-secret-token"
  },
  "notifications": {
    "default_timeout": 0,
    "default_sound": true,
    "default_urgency": "normal"
  },
  "scripts": {
    "timeout": 30000,
    "notify": [
      {
        "type": "shell",
        "path": "/home/user/scripts/notify-log.sh",
        "enabled": true
      }
    ]
  },
  "logging": {
    "retentionHours": 168
  },
  "platforms": {
    "linux": {
      "sound_enabled": false
    }
  }
}

项目配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "notifications": {
    "default_urgency": "critical",
    "title_template": "[PROJECT] {tool_name} - {project_name}"
  },
  "scripts": {
    "notify": [
      {
        "type": "node",
        "path": "/path/to/project/scripts/notify.js",
        "enabled": true
      }
    ]
  }
}

实际使用场景

实际有些简单的场景：

1. 多任务并行处理

当同时运行多个 AI 任务时，AI Common Notify 能帮助您：

1
2
3
4
5
6
# 在不同项目中启动AI任务
# 任务1: Claude Code重构代码
# 任务2: Cursor生成文档
# 任务3: Windsurf优化性能

# 每个任务完成后都会收到通知，您可以根据紧急程度安排处理顺序

2. 长时间运行任务监控

对于需要长时间运行的 AI 任务，您可以设置完成后通知：

1
2
# 在脚本中集成
ai-common-notify send --title "模型训练完成" --message "模型训练已完成，准确率95.2%"

3. 错误警报系统

在 CI/CD 流程中集成关键错误通知：

1
2
3
4
# 检测到错误时发送关键通知
if [ $ERROR_CODE -ne 0 ]; then
  ai-common-notify send --title "构建失败" --message "构建过程出现错误，请检查日志" --urgency critical
fi

4. 自动化工作流

在自动化脚本中使用 AI Common Notify：

1
2
3
4
#!/bin/bash
echo "开始部署..."
# ... 部署过程 ...
ai-common-notify send --title "部署完成" --message "应用已成功部署到生产环境"

总结

AI Common Notify 通过提供统一的通知接口，有效解决了 AI 编程工具生态中通知机制缺失的问题。它不仅支持多种主流 AI 工具，还提供了灵活的配置选项、强大的脚本扩展能力和 REST API，满足不同用户的使用需求。